HoWSample is a minimal sample application, and doesn’t really do anything useful, except that its help file (which you are reading) serves as the manual for the Help on Wheels developer’s kit. The source code provided with HoWSample shows you how to make your application into a client of the Help on Wheels help server application, just like this one. This code is provided on an as-is basis for your benefit, and is not warranted in any way. The author, Ross Brown, will not be responsible for any consequence of the use of this application or its source code.
Help on Wheels is a free help server which provides on-line help service for client applications running on the same Macintosh computer. It offers its clients a simple, consistent user interface model, which includes client indexing, a table of contents, and a flexible hypertext capability. Client applications are smaller than they would be if they provided their own help interface, as they can ignore the difficult matters of displaying, saving, and printing styled help text.
\endkeep
When you write a client application, you use a simple five-function interface library, HoWLib, to communicate with the help server. These functions direct a small client engine which you link into your application. Once registered, this engine tracks the help server, launching and re-launching it as required. It also detects “Help events” sent by the server when the user clicks on “hot” hypertext buttons, and feeds them back to you via a handler you provide.
When you release your product, you can freely include a copy of Help on Wheels in the distribution, or direct users to a place where they can find a copy. The server requires no special installation. If a user asks for help from your application, and the help server is not present on any mounted volume, the client engine offers to save the help text as a TeachText document, and opens it for the user.
Your help text and pictures are stored in a standard, server-friendly compiled form in one or more help files, of which only one is active at a time. If you want to ensure that help is always available, you may build the help information into the application itself, so that the application file is also the help file. Otherwise, your help file is a separate document, which can be stored separately, archived, or trashed. Because your separate help file is a Help on Wheels document, the user can open or print it without opening your application, so there may be no need to provide any other form of documentation in your package.
Because any application can be a client, Help on Wheels offers background-only applications a handy method of interacting with the user, more sophisticated than the Notification Manager.
Programs which are not applications (system extensions, Chooser extensions, control panels, etc.) can also be documented using help files, but cannot register with the server as applications do, because they are not distinct processes under the Macintosh Operating System. If you want to offer an on-line help facility for such a program, you can add a Help button, or detect the Help key at startup, and call a HoWLib function to tell the server to open the help file. This request will automatically wait for startup to complete, if necessary.
Help on Wheels supports multilingual help files, selecting a language based on the current System environment.
\str#
\keep
\tag 1200
\tcon Contents
\only screen
\pict 1200
\only print save
\style bold
\just center
\size 140
Contents
Here is a list of contents for the Help on Wheels developer’s kit:
\endkeep
• HoWSample — a folder containing the HoWSample application and source code
• HoWSample — the application
• HoWSample Help — the help file
• Icons.h — an update to the MPW 3.2 version, required by HoWSample.c
• HoWS.make — the Make file for the HoWSample application
• HoWSample.c — the C source file for the HoWSample application
• HoWSample.doc — the help source document for the HoWSample application
• HoWSample.h — an internal header file for HoWSample.c
• HoWSample.picts — the resource file containing pictures for the help file
• HoWSample.r — the Rez source file for the HoWSample application
• HoWSample.r.h — an internal joint Rez/C header file for HoWSample.[rc]
• HoWSample.sounds — the resource file containing sounds for the HoWSample application
• HoWLib.h — the header file for the HoWLib client interface library
• HoWLib.o — the HoWLib client interface library
• HoWRez.English.r — the English version of the basic client Rez file
• wrap — an MPW tool to wrap flowing document text into separate lines
• cvrt — an MPW tool to convert wrapped document text to resources
\str#
\keep
\tag 1300
\tcon Requirements
\only screen
\pict 1300
\only print save
\style bold
\just center
\size 140
Requirements
The current version of the Help on Wheels developer’s kit is available only for use with MPW C and C++. MPW Pascal developers can use the kit with a little work, since it uses Pascal calling conventions. The next version will support Think C projects.
\endkeep
Help on Wheels uses several Toolbox managers which are new to System 7, such as the Alias Manager, the Process Manager, and the Apple Event Manager. Therefore, it does not work under System 6 or earlier versions, and any attempt to register a client will be met with an error code. (Later versions of Help on Wheels and its client interface library will operate under System 6 in a reduced mode, where the server deals only with help files and does not talk back to clients.)
To be a client of the help server, an application must be System 7 friendly. This is because the client engine and server converse using Apple events. Once you set the bit in your application’s 'SIZE' resource to allow this behavior, Finder assumes that you support the Required suite of events. These events, Open Application, Open Documents, Print Documents, and Quit Application, are fully documented in Inside Macintosh, Volume VI, and elsewhere. Beyond that, Help on Wheels requires no special knowledge of Apple events.
Client applications should be able to receive events while running in the background. This is not a requirement, and foreground-only applications can still receive Help events, because the server always brings the client into the foreground before sending a Help event.
For consistency, your application should support two methods of invoking help. First, it should add one or more entries to the Help menu which the user can select to get help on the entire application or on a specific topic. Second, it should react to the Help key (ASCII character value 5) and Command-? key combination (for keyboards which lack a Help key) in all modes, including dialogs, and in a context-sensitive fashion, displaying a topic relevant to what the user is seeing.
NOTE: Modal dialogs disable entries you place in the Help menu, and they also prevent the client engine from bringing the server to the foreground when the user presses the Help key. The HoWSample source code contains a sample modal dialog filter procedure which automatically hides and unhides modal dialogs so that this is not a problem.
If your help file is separate from your application file, you are responsible for keeping track of its movements between sessions; the server keeps track during sessions. One good way is to locate the help file at registration time by resolving an alias record which is relative to your application file. You should store this alias record as a resource in your application file, and keep an updated version in your preferences file from session to session. While resolving this alias record, you should be careful to specify no user interaction, so the user won’t see an AppleShare password dialog if operating with a borrowed preferences file. (If this all sounds confusing, take heart. The utility function HoWFindHelpFile in the HoWLib interface library takes care of this entire procedure, and the HoWSample source code shows how to call it.) To create such an alias record while building your application, ask Finder to make an alias to the help file, and pull the contained alias resource into your application file using Rez. If the help file is in a different folder from the application file, you should first move the alias to the application file’s folder, then do a “Find Original” on it to force Finder to update its relativity data. You should also do a “Find Original” to update the alias whenever the help file’s creation date changes. (Again, the HoWSample source code and Make file shows how to do all this.) If you don’t like the approach of using alias records to track the help file, you can either merge the help data into the application, or keep it separate and tell your users not to move one file without the other.
\str#
\keep
\tag 1400
\tcon Building a Help File
\only screen
\pict 1400
\only print save
\style bold
\just center
\size 140
Building a Help File
Here, I describe briefly what you have to do to make a help file. These instructions apply whether or not you’ve decided to make the help file a real document, separate from your application.
\endkeep
\keep
\tag 1410
\only screen
\tcon What It Is
\only print
\tcon What Is a Help File?
\style bold
\size 120
What Is a Help File?
Your Help on Wheels client application must have a help file, which the server can open when it’s time to display help. When it opens your help file, the server needs to find and display the information fast. Reading a mixed text/graphic format would take too long, so Help on Wheels uses a special format designed by John Norstad for his famous Disinfectant anti-virus application. This format consists of a collection of resources which can be quickly read and translated into a list data structure, complete with text, pictures, and indexing information. As improved for use with Help on Wheels, this format also allows for hypertext buttons and multilingual help files.
\endkeep
\keep
\tag 1420
\only screen
\tcon How to Make It
\only print
\tcon How Do I Make One?
\style bold
\size 120
How Do I Make One?
You will need the special “wrap” and “cvrt” MPW tools and the Rez file HoWRez.{language}.r, provided in this developer’s kit, to produce a help file in this format. (A note to those familiar with Norstad’s source archive: These tools are not quite the same as the ones he provided, but they do use the same syntax, so the syntax description included here is his. The tools provided are guaranteed to work correctly for all uses described in these instructions. Please address any questions about these tools to me, not to Mr. Norstad.) The HoWSample Make file shows how the tools and Rez file were used to build this help file.
\endkeep
You may have noticed that this help file, viewed through the help server, is a mixture of pictures and text. The help source document, however, is a plain text file. When reading this section, you may want to compare what you see through Help on Wheels with the help source document.
To produce a help source document for your application, you can use any text editor which wraps long lines and is able to “save as text.” TeachText is fine; Microsoft Word is good too, as long as you remember to “save as text” and not to edit the pictures into the “.doc” file itself. MPW Shell is not good for this purpose, because it doesn’t wrap long lines.
\keep
\tag 1430
\only screen
\tcon Source Document
\only print
\tcon What’s in a Source Document?
\style bold
\size 120
What’s in a Source Document?
The paragraphs you see in a help file like this one are just long lines of text in the help source document, with no carriage returns between lines. (The “wrap” tool does the line wrapping for you; the help server will re-wrap the lines when printing, according to the user’s Page Setup specifications.) There are usually two carriage returns between paragraphs, to ensure some white space between.
\endkeep
Everything in a help source document that isn’t paragraph text is a markup directive. These directives are similar to those of markup languages such as GML and nroff. For example, the pictures you see in this help file are stored in the help file as 'PICT' resources. They were positioned between paragraphs using a simple markup directive in the help source document:
\just center
\style italic
\pict 429
Other markup directives let you set the justification and style of a paragraph, like the centered italic text you have just read. You also use markup directives to put entries in the table of contents, break pages, build keep blocks, and so on.
\keep
\tag 1440
\only screen
\tcon How to Index It
\only print
\tcon How Do I Index My Help File?
\style bold
\size 120
How Do I Index My Help File?
The table of contents built from your markup directives appears in the server’s help window, so that the user can browse by topic. It also appears, complete with page numbers, at the front of the help file when printed. This method of indexing your help file is suitable for humans, but not for your client application.
\endkeep
The other important use of markup directives is to put numeric tag values on important points in the help file. Tags have two main uses in Help on Wheels help files. First, they allow the client to summon information on a specific topic by citing a tag value when asking the server to display the help file. The server will scroll the help file to make the tag point visible. Second, they introduce blocks of information which the user can click to cause an action. These hypertext “buttons” may be single paragraphs or pictures, or several together, such as a figure and its caption.
Hypertext tags are worth a closer look, because they can add a lot to the impact of your help file. Hypertext buttons in Help on Wheels are of two types: link buttons and hot buttons. When the user clicks a link button, the server scrolls to another part of the help file to display related information. With a hot button, the server activates the client and sends it a Help event, telling it which button was clicked. Your client can respond in any way you think is appropriate.
Hypertext tags are distinguished from ordinary tags by their negative numbers. (Conventionally, hypertext paragraphs are underlined, but you must insert the style directive to make this happen.) The button extends from the hypertext tag to the next tag. You can use a “\tag 0” directive to end a hypertext block, if you have no other reason to put a tag there. The button is a link button only if there is another tag in the help file whose number is the same, but positive, indicating the target of the link. If there is no complementary target for the hypertext tag, then the button is a hot button.
\keep
\tag 1450
\only screen
\tcon Putting Together
\only print
\tcon Putting It Together
\style bold
\size 120
Putting it Together
Here I describe what MPW commands you need to build a help file. You should make these commands part of your Make file, as is the case with HoWSample.
\endkeep
The MPW tools “cvrt” and “wrap” can be piped together, so that your help source document goes in one end, and your help file comes out the other. The following option values are standard for use with Help on Wheels: “wrap -r 335 -p”; “cvrt -w 345 -h 12”. In addition, “cvrt” needs to know the name of the file where the 'PICT' resources are stored (“-p”), and the ID numbers for the generated 'STR#' (“-i”), 'TCON' (“-t”), 'TAG ' (“-g”), and 'CELL' (“-c”) resources. There may actually be several 'STR#' resources, depending on the length of the source document and the number of “\str#” directives in it.
[The following descriptions are reprinted from the source by John Norstad.]
\keep
wrap -r xxxx [-p]
xxxx = right margin in pixels.
-p = if specified, add a special end-of-paragraph byte 31 to the end of each line.
The text file is converted to a consecutive sequence of STR# resources starting with id nnn.
The source text is intermixed with special cvrt directives. Any line starting with the character ‘\’ is treated as a directive. Directives must be all lower case. The syntax checking by this tool is minimal.
\endkeep
\keep
\style italic
\str#
Starts a new STR# resource.
\endkeep
\keep
\style italic
\tcon title
Table of contents entry. The title and the current line number (zero based) are saved in the TCON resource.
\endkeep
\keep
\style italic
\tag nnn
Tag resource entry. The number nnn and the current line number (zero based) are saved in the TAG resource.
\endkeep
\keep
\style italic
\style xxx xxx xxx
The next text line is drawn in the specified style or styles. xxx may be any of the following:
normal (default)
bold
italic
underline
outline
shadow
condense
extend
\endkeep
\keep
\style italic
\just xxx
The next text line or picture is drawn with the specified justification. xxx may be any of the following:
left (default for text lines)
center (default for pictures)
right
\endkeep
\keep
\style italic
\size xxx
Print the following line of text xxx% larger than normal. Printing only. The normal font size is multiplied by xxx%, then truncated. For non-laserwriters it is then rounded down to the nearest font size which can be printed without Font Manager scaling.
\endkeep
\keep
\style italic
\only xxx xxx
The next text line or picture or table of contents entry should only be output as specified. xxx may be any of the following:
screen Only in the report on the screen.
print Only in the printed document.
save Only in the saved document.
The default for text lines is: screen print save
The default for pictures is: screen print
The default for tcon entries is: screen print
\endkeep
\keep
\style italic
\pict id
A picture from the pict resource file should be inserted at this point. “id” is the resource id of the pict.
\endkeep
\keep
\style italic
\page noheader
Start a new page. Printing only. The “noheader” parameter is optional. If the parameter is present, header printing is disabled until the next “\page” directive is encountered.
\endkeep
\keep
\style italic
\keep
Keep the following block of text on the same page. Force a page break if necessary. Printing only. Paragraphs are always kept on a page, never split across page boundaries.
\endkeep
\keep
\style italic
\endkeep
End a keep block. Printing only.
\endkeep
\keep
\style italic
\itcon nnn
Insert table of contents. Printing only.
nnn = total number of printing tcon entries. This number must be adjusted by hand whenever you add or remove tcon entries (sorry). It is verified at the end of the cvrt run, and if it is incorrect the correct value is printed in an error message (this helps a bit).
\endkeep
The same ID numbers you gave to “cvrt” should also appear in the Rez command as values for the defined symbols “HoWi”, “HoWt”, “HoWg”, and “HoWc”. Another symbol “HoWa” specifies the ID number of the generated 'ALRT', 'DITL', and 'STR ' resources. If your help file is the application itself, be careful not to choose ID numbers which collide with any defined for your application’s own use. All of these ID numbers should be in the range allocated for applications (128 to 32767). The defined symbol “languageCode” can also be set.
\tag -1500
\style underline
See the section entitled “Language Support” for more details.
\tag 0
If your help file is separate from your application, it must have type 'HoW!' and creator 'HoW?' in order to be a double-clickable Help on Wheels document. As well as the necessary “-t” and “-c” options, your Rez command should include an option of the form “-d application=∂"HoWSample∂"” (or “-d extension=∂"HoWSampleExt∂"” if your program is an extension or control panel) to direct HoWRez.{language}.r to generate an alert string resource, which will help the user get a readable TeachText version if the server is not available.
It is likely that your documentation will change over time. If your help file is separate from your application, new versions of the help file may be incompatible with old versions of the application, and vice versa. To help prevent errors, Help on Wheels offers an optional client version checking capability. To use it, include options of the form “-d version=0x0101 -d versionString=∂"1.0.1∂"” in your Rez command. This will direct HoWRez.{language}.r to generate a version resource, visible using Finder’s Get Info dialog. HoWSample’s Make file and C source code show how to tie these options to the application so that version checking is enforced. If the help file contains a version resource, and the version code is not the same as that supplied by the application at the time of registration, an error (wrongVersionErr) is returned to the application.
You will need a separate Rez command to merge the 'PICT' resource file into the help file, because the “cvrt” tool doesn’t do this for you. The HoWSample Make file shows one way to do this.
\str#
\keep
\tag 1500
\tcon Language Support
\only screen
\pict 1500
\only print save
\style bold
\just center
\size 140
Language Support
You may have designed your client application to offer a multilingual user interface in a single international version. Or perhaps it’s too much work to localize your application for 20 different languages, so you decide to translate only the help information. Even if you distribute different versions of your application for each market, you may not want to maintain different versions of the help file, or you may want to support two languages in each market: the local one, and English. Since the help file is the first thing your users will read, language support may be important to you. Not only can the Help on Wheels server be localized for other languages; it supports multilingual help files.
\endkeep
NOTE: This version of Help on Wheels does not support script systems which characteristically differ from the standard smRoman (0). Support for other world script systems is possible in the future.
\keep
\tag 1510
\only screen
\tcon What User Sees
\only print
\tcon What Does the User See?
\style bold
\size 120
What Does the User See?
When Help on Wheels opens your help file, it follows a sequence to find the most appropriate available language. First, it always tries to find help information corresponding to the current script’s current language code. Second, failing that, it will use the language code of the server’s local version, as specified in its own 'HoWL' resource. Third, it will use the default language code indicated by the client at registration. Last, it will try langEnglish (0). If even that fails, the user may see an error message, and your client will receive an error code (noMasterResErr) at the time of registration.
\endkeep
To offer help in 20 languages, you can distribute 20 small help files, or one large one. If you use multiple files, your application is responsible for registering the right one at startup. If you use one file, Help on Wheels will determine the “right” language as above, and select one of the 20 parallel sets of resources in the help file.
\keep
\tag 1520
\only screen
\tcon Multilingual Help
\only print
\tcon How Do I Build Multilingual Help Files?
\style bold
\size 120
How Do I Build Multilingual Help Files?
If you want to support 20 languages in one help file, you must write 20 help source documents, and repeat the build sequence (cvrt, wrap, Rez) 20 times, targeting the same file each time. Each time, you are adding a master 'HoW!' resource, with ID equal to the language code, which points to many other resources containing the help information. You must use different values for the “HoW…” defined symbols for each language, to avoid collisions among these other resources. Naturally, when translating the help source documents, you will use the same tag values to index the same topics in the help file for each language.
\endkeep
There is a different version of the resource file HoWRez.{language}.r for each language. The difference between HoWRez.English.r and HoWRez.French.r is twofold. First, the default language code is different, so if your help source document is in French and you build it with HoWRez.French.r, you don’t have to define the “languageCode” symbol in the Rez command. Second, French will be the language of the strings in the alerts and dialog boxes seen by the user if the help server could not be found to display the help file. If your help file is separate from your application, you should define the “application” or “extension” symbol in only one of the Rez commands, the one which builds with the main language’s HoWRez.{language}.r file, to ensure that the Finder alert string 'STR ' (-16397) comes up in the main language.
\str#
\keep
\tag 1600
\only screen
\tcon Client-Server
\only print
\tcon Client-Server Relations
\only screen
\pict 1600
\only print save
\style bold
\just center
\size 140
Client-Server Relations
This section explains how a client conducts its relations with the help server, with the help of the HoWLib client interface library.
\endkeep
\keep
\tag 1610
\only screen
\tcon Client Engine
\only print
\tcon The Client Engine
\style bold
\size 120
The Client Engine
The interface, described in the next subsection, consists of two utility functions, HoWFindHelpFile and HoWOpen, and three client engine functions, HoWRegister, HoWDisplay, and HoWDeregister. Your application will generally find its help file and register on entry, display in response to menu, mouse, and key events, and deregister on exit. Apart from that, the only requirement is to call AEProcessAppleEvent when you receive any high-level event that isn’t known not to be an Apple event, which is generally good practice.
\only screen
\tag -42
\style underline
(Click this hot button to hear what famous Apple product doesn’t play by the rules.)
\tag 0
\endkeep
If your program is not an application, it cannot use client engine functions. It can call HoWFindHelpFile to find its help file if it is separate, and it can call HoWOpen to tell the server to open the help file (starting the server if necessary). It cannot communicate with the server using tags, neither for display nor for Help events.
When you register, you have the option of starting the server immediately, or deferring until the first display. Unless the server’s availability is critical to your application, you will usually choose the latter, less obnoxious, option.
The client engine handles the rest of the relationship between client and server. Your application doesn’t have to care where the server is, or whether it’s running already, or what to do if the user exits the server while your application is running. The client engine, contained in a purgeable code segment named “HoWLib,” manages these details for you. If the server is started by some other method while your application is running, the engine senses this, and makes sure that the server adds your application to its Help menu. The engine also takes care of Help events by invoking your handler, if you have one.
If you call HoWDisplay when the server is not started, and the server can’t be found on any mounted volume, the engine posts an alert, offering to save the help text as a TeachText document. If the user agrees, the engine creates the file and opens it automatically. If the file would be too large for TeachText to open, the engine breaks it into several files and puts them in a new directory.
\keep
\tag 1620
\tcon Casual Displays
\style bold
\size 120
Casual Displays
HoWSample is a very simple client application which demonstrates good client practices. Whenever the user selects the main Help menu item or presses the Help key, it calls HoWDisplay with “tag” set to 0, or if a dialog is open, some tag value appropriate to the cursor location. Subsidiary items in the Help menu cause calls to HoWDisplay with other tag values, demonstrating how a client can index the help file.
\endkeep
HoWSample also demonstrates how you can implement context-sensitive help using casual displays. The “casual” argument to the HoWDisplay function is always false when HoWSample calls it in reaction to a direct user action. HoWSample requests a casual display whenever the user selects a menu item or clicks on a dialog item. Setting “casual” to true makes the call more of a hint to the server, and less of an order. This mechanism allows the client to use the server’s optional “follow” mode, effectively taking control of the help display.
Specifically, casual displays are different in the following ways: First, they do not start the server if it isn’t running. Second, they do not bring the server into the foreground. Third, they are ineffective if the server is not already displaying the client’s help file. Fourth, they are ineffective if the user has not selected the “follow” option in the server’s Preferences dialog.
\keep
\tag 1630
\only screen
\tcon HoWLib Interface
\only print
\tcon HoWLib Client Interface Library Functions
\style bold
\size 120
HoWLib Client Interface Library Functions
This subsection describes exactly what the HoWLib functions do, and how and when to call them, quoting from the C header file. You may want to follow along in the HoWSample source code as you read these function descriptions.
\endkeep
\keep
/* The Help event handler receives an event id which is the negative of the tag associated with the clicked text. */
/* Find the help file referenced by the 'alis' resource with ID "aliasResID" in the resource file with ID "preferencesFileRefNum", or in the resource file with ID "applicationFileRefNum" if the resource does not exist in the preferences file or cannot be resolved. The alias record, possibly changed by UpdateAlias, is written back to the preferences file if possible. The application file is not changed. Resolution is relative to the application file, so it can take advantage of relative information in the alias resource if present. If the help file cannot be found by a fast search, one exhaustive search will be done on the alias record in the application file. A failed exhaustive search is noted in the preferences file so that it is not repeated; this note remains until the preferences file is deleted, or until a later fast search successfully finds the help file. If you do not maintain a separate preferences file, set both resource file IDs to the same value, and the application file will be treated as though it were also the preferences file. */
/* Register or re-register with the help server. The help file may be any file, including the main application file. If the help file has a 'vers'(1) resource, and the version (first word) does not match "version", wrongVersionErr is returned. If there is no master resource in the help file for the current script's current language, nor for "defaultLanguage", nor for langEnglish, noMasterResErr is returned. The server will prefer to use its own language over "defaultLanguage". By re-registering, the client can switch to another help file. If the server is not already started, and "startServer" is true, HoWRegister will try to start the server, which may result in many OS error codes, as well as noServerApplErr, a non-fatal code returned for your information (see HoWDisplay below). If the server is not already started, and "startServer" is false (which it should be for most clients), the usual return code is noErr, meaning that the actual registration has been deferred until the first non-casual display (see below) or until the server starts by some other method. Gestalt checks may result in other error codes listed above; the expected error code under System 6 is noAppleEventsErr. The Help event handler is optional; pass nil if the client does not support them. */
pascal OSErr HoWRegister (const FSSpec *helpFile, short version,
LangCode defaultLanguage, Boolean startServer,
HoWHandlerProcPtr handler);
\endkeep
\keep
/* Display the help file at the indicated tag position. If "tag" is zero, the last seen position is retained. If the server is not already started, and "casual" is false, this will attempt to start the server; if the server is absent, the user sees an alert offering to save a readable copy using TeachText and open it for viewing, unless the client is background-only, in which case no alerts appear, and the document is created on the desktop. A casual display is effective only if the server is started and running in the background, with the "follow" option in effect, and already displaying this client's help file. A casual display always leaves the client in the foreground; a non-casual display always brings the server to the foreground. Note that modal dialogs will prevent the server from coming to the foreground unless they are hidden before this call. */
/* Deregister with the help server. If the client fails to deregister before it exits, the server will deregister it automatically. */
pascal OSErr HoWDeregister (void);
\endkeep
\keep
/* Launch the help server, if necessary, to open and display the given help file. This method is suggested for use by programs which are not applications; applications should use HoWRegister instead (see above). If the server is absent, a TeachText copy is created on the desktop and opened (as for a background-only application calling HoWDisplay). Version checking is not performed, and the current script's current language is always used. This may be called by 'INIT' logic in control panels or extensions, because it uses the Notification Manager; allow 5000 bytes when calculating the system heap requirement for your 'sysz' resource. */
pascal OSErr HoWOpen (const FSSpec *helpFile);
\endkeep
\str#
\keep
\tag 1700
\tcon Dialogs
\only screen
\pict 1700
\only print save
\style bold
\just center
\size 140
Dialogs
HoWSample has one dialog, to illustrate how to attach help information to items in a dialog.
\endkeep
\keep
\tag 1710
\tag 13000
\only screen
\tcon Do-Nothing
\only print
\tcon The Do-Nothing Dialog
\style bold
\size 120
The Do-Nothing Dialog
\pict 1711
\only screen print
This dialog appears when you select the Do-Nothing command from the Demo menu.
\endkeep
\keep
\tag 13001
• Squeak button
This button emits an objectionable noise when pressed. It also closes the dialog.
\endkeep
\keep
\tag 1720
\tag 12800
\only screen
\tcon About
\only print
\tcon The About Dialog
\style bold
\size 120
The About Dialog
This dialog presents HoWSample’s About box. It is opened by the “About HoWSample…” command in the Apple menu.
\endkeep
It mentions, by way of a balloon, that HoWSample offers help through both Balloon Help and Help on Wheels. If you already have balloons showing, HoWSample spares you the balloon, figuring that you’ve probably seen enough recently.
\str#
\keep
\tag 1800
\tcon Menus
\only screen
\pict 1800
\only print save
\style bold
\just center
\size 140
Menus
This section describes each of HoWSample’s menus.
\endkeep
\keep
\tag 1810
\tag 25600
\only screen
\tcon Apple
\only print
\tcon The Apple Menu
\style bold
\size 120
The Apple Menu
\tag 25601
• About HoWSample…
This command opens HoWSample’s About dialog, which invites you to try Balloon Help or Help on Wheels to learn more about HoWSample.
\endkeep
\keep
\tag 1820
\tag 25700
\only screen
\tcon File
\only print
\tcon The File Menu
\style bold
\size 120
The File Menu
\pict 1821
\only screen print
\tag 25701
• Quit (Command-Q)
This command quits HoWSample.
\endkeep
\keep
\tag 1830
\tag 25800
\only screen
\tcon Edit
\only print
\tcon The Edit Menu
\style bold
\size 120
The Edit Menu
\pict 1831
\only screen print
\tag 25801
• Undo (Command-Z)
This command is not used by HoWSample. It is present only for desk accessories.
\endkeep
\keep
\tag 25803
• Cut (Command-X)
This command cuts selected text to the clipboard. It is used only with desk accessories and dialogs containing text fields.
\endkeep
\keep
\tag 25804
• Copy (Command-C)
This command copies selected text to the clipboard. It is used only with desk accessories and dialogs containing text fields.
\endkeep
\keep
\tag 25805
• Paste (Command-V)
This command inserts the contents of the clipboard at the current cursor location or replaces the currently selected text by the contents of the clipboard. It is used only with desk accessories and dialogs containing text fields.
\endkeep
\keep
\tag 25806
• Clear
This command clears the selected text in a desk accessory or dialogs containing text fields.
\endkeep
\keep
\tag 1840
\tag 25900
\only screen
\tcon Demo
\only print
\tcon The Demo Menu
\style bold
\size 120
The Demo Menu
\pict 1841
\only screen print
\tag 25901
• Do-Nothing… (Command-D)
This command does nothing, except bring up the do-nothing dialog.
\tag -1710
\style underline
See the section entitled “The Do-Nothing Dialog” for more information about the do-nothing dialog.
\tag 0
\endkeep
\keep
\tag 1850
\only screen
\tcon Help
\only print
\tcon The Help Menu
\style bold
\size 120
The Help Menu
\pict 1851
\only screen print
• About Balloon Help…
This command, supplied by System software, tells you how to use Balloon Help. HoWSample supports Balloon Help.
\endkeep
\keep
• Show/Hide Balloons
This command, supplied by System software, lets you turn Balloon Help on and off. HoWSample supports Balloon Help.
\endkeep
\keep
• HoWSample Help
This command asks Help on Wheels to display HoWSample’s help file. This will start the help server if it was not already running. If the help server cannot be found on any mounted volume, HoWSample will offer to save a readable copy of the help file as a TeachText file, then ask Finder to open the file. If the help file is missing or invalid, this command is disabled.
\endkeep
Pressing the Help or Command-? key at any time does the same thing. When there is a dialog box on your screen, such as the do-nothing dialog, the menu command is disabled, and the keyboard is the only way to display help.
\keep
• Dialog Help
This command does the same thing as the HoWSample Help command, but scrolls the help display to show the section entitled “Dialogs.”
\endkeep
\keep
• Menu Help
This command does the same thing as the HoWSample Help command, but scrolls the help display to show the section entitled “Menus.”
\endkeep
\keep
\tag 1900
\tcon Revision History
\only screen
\pict 1900
\only print save
\style bold
\just center
\size 140
Revision History
\style italic
1.1 (March 28, 1994)
• Public AWOL Utilities 1.1 release.
\style italic
1.0.5 (March 27, 1994)
• No revisions.
\style italic
1.0.4 (March 13, 1994)
• Added support for an “extension” symbol in HoWRez.{language}.r, so that a useful message is generated if the user tries to open or print an extension or control panel’s separate help file when the help server is absent.
\style italic
1.0.3 (February 27, 1994)
• Corrected an incompatibility with SpeedyFinder7’s Help menu removal option which prevented help display.
• Corrected an error in the documentation of HoWFindHelpFile.
• Allowed the application to operate without a preferences file (for example, when startup disk is locked).
\style italic
1.0.2 (January 30, 1994)
• No revisions.
\style italic
1.0.1 (January 19, 1994)
• If the help server is absent when HoWSample requests help, and the user agrees to save the help file as a TeachText document, the file is split into parts small enough for TeachText to handle.
• Added HoWOpen function to HoWLib. Control panels and extensions can now launch the server to show their help files.
• Calls to HoWOpen and background-only calls to HoWDisplay now cause no-alert TeachText document launch if server is absent.
• Corrected bug in cvrt tool which gave too much or too little vertical space to pictures.
• Appended “ •” to name of text file saved by HoWDisplay or HoWOpen, to avoid collision with help file.
